<!-- HTML header for doxygen 1.8.3.1-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.3.1"/>
<title>AngelScript: Return references</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<script type="test/javascript" src="touch.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
  $(window).load(resizeHeight);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Logo" src="aslogo_small.png"/></td>
  <td style="padding-left: 0.5em;">
   <div id="projectname">AngelScript
   </div>
  </td>
   <td>        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
</td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.3.1 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('doc_script_func_retref.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Classes</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark">&#160;</span>Pages</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">Return references </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>A function can also return references, which will allow the caller to modify the value pointed to by the reference. To declare a function that return a reference include the &amp; symbol between the return type and name of the function. Add const before the type if the reference should be read only, i.e. it shouldn't be possible to modify the value it points to.</p>
<pre>
  int property;
  int &amp;Function()
  {
    // Return a reference to the property
    return property;
  }</pre><pre>  void main()
  {
    // Modify the value pointed to by the returned reference
    Function() = 1;
  }
</pre><p>Due to the need to guarantee that the reference is valid even after the function returns to the caller there exist certain restrictions. You don't need to try to remember these restrictions as the compiler will give an error if you they are violated, but if you do encounter a compile error when returning a reference it will be good to understand why it is happening so that you can determine how to avoid it.</p>
<h1><a class="anchor" id="doc_script_retref_global"></a>
References to global variables are allowed</h1>
<p>As a global variable is in the global scope, the lifetime of the variable is longer than the scope of the function. A function can thus return a reference to a global variable, or even member of an object reached through a global variable.</p>
<h1><a class="anchor" id="doc_script_refref_member"></a>
References to class members are allowed</h1>
<p>A class method can return a reference to a class property of the same object, because the caller is required to hold a reference to the object it is known that the member will exist even after the method returns.</p>
<p>The class method is also allowed to return reference to global variables, just like any other function.</p>
<h1><a class="anchor" id="doc_script_retref_local"></a>
Can't return reference to local variables</h1>
<p>Because local variables must be freed when the function exits, it is not allowed to return a reference to them. The same is also true for any parameters that the function received. The parameters are also cleaned up when the function exits, so they too cannot be returned by reference.</p>
<h1><a class="anchor" id="doc_script_retref_deferred"></a>
Can't use expressions with deferred parameters</h1>
<p>For some function calls with arguments, there may be a necessary processing of the arguments after the function call returned, e.g. to clean up the input object, or to assign the output parameters. If the function that was called is returning a reference, then that reference cannot in turn be returned again, as it may be invalidated by the deferred evaluation of the arguments.</p>
<h1><a class="anchor" id="doc_script_refref_cleanup"></a>
Can't use expressions that rely on local objects</h1>
<p>All local objects must be cleaned up before a function exits. For functions that return references this clean-up happens before the return expression is evaluated, otherwise the cleanup of the local objects may accidentally invalidate the reference. For this reason it is not possible to use expressions that rely on local objects to evaluate the reference that should be returned.</p>
<p>Primitive values can be used though, as these do not require cleanup upon exit. </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated on Sun Dec 18 2016 12:35:30 for AngelScript by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.3.1 </li>
  </ul>
</div>
</body>
</html>
